<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Compact XML</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 6253 2010-03-02 00:24:53Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: left }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
<style type="text/css">

body { background-color: gray; }
div.document { margin: 10px; padding: 10px; color: black; background-color: white; border: solid silver 3px; margin-left: 280px;}
div.document#gizmo-documentation { margin: 10px; }
#contents { float: left; padding: 10px; border: solid silver 3px; width: 280px; margin: 0; margin-left: -300px; border-left: 0; background-color: white;}
#contents ul.simple { padding-left: 0; list-style-position: inside; }
#contents ul { padding-left: 1em; }
div.section { margin-left: 17px; }
div.section div.section { margin-left: 1em; }
pre { overflow-x: auto; }

</style>
</head>
<body>
<div class="document" id="compact-xml">
<h1 class="title">Compact XML</h1>

<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#overview" id="id12">Overview</a></li>
<li><a class="reference internal" href="#tutorial" id="id13">Tutorial</a></li>
<li><a class="reference internal" href="#syntax" id="id14">Syntax</a></li>
<li><a class="reference internal" href="#expressions" id="id15">Expressions</a><ul>
<li><a class="reference internal" href="#literals" id="id16">Literals</a></li>
<li><a class="reference internal" href="#names" id="id17">Names</a></li>
<li><a class="reference internal" href="#continuations" id="id18">Continuations</a></li>
<li><a class="reference internal" href="#value-expressions" id="id19">Value Expressions</a></li>
<li><a class="reference internal" href="#name-expressions" id="id20">Name Expressions</a></li>
<li><a class="reference internal" href="#in-line-expressions" id="id21">In-Line Expressions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#statements" id="id22">Statements</a><ul>
<li><a class="reference internal" href="#id1" id="id23">Element (<tt class="docutils literal">&lt;</tt>)</a></li>
<li><a class="reference internal" href="#element-macro-no-prefix" id="id24">Element Macro (<tt class="docutils literal">No Prefix</tt>)</a></li>
<li><a class="reference internal" href="#id2" id="id25">Attribute (<tt class="docutils literal">&#64;</tt>)</a></li>
<li><a class="reference internal" href="#id3" id="id26">Attribute Group (<tt class="docutils literal">&#64;&#64;</tt>)</a></li>
<li><a class="reference internal" href="#id4" id="id27">Namespace (<tt class="docutils literal">#</tt>)</a></li>
<li><a class="reference internal" href="#id5" id="id28">Text (<tt class="docutils literal">&quot;</tt>)</a></li>
<li><a class="reference internal" href="#id6" id="id29">Comment (<tt class="docutils literal">!</tt>)</a></li>
<li><a class="reference internal" href="#id7" id="id30">Processing Instruction (<tt class="docutils literal">&lt;?</tt>)</a></li>
<li><a class="reference internal" href="#id8" id="id31">Document Type Declaration (<tt class="docutils literal">&lt;!</tt>)</a></li>
<li><a class="reference internal" href="#attribute-group-definition-command-attribute" id="id32">Attribute Group Definition Command (<tt class="docutils literal"><span class="pre">?attribute</span></tt>)</a></li>
<li><a class="reference internal" href="#comment-command-comment" id="id33">Comment Command (<tt class="docutils literal"><span class="pre">?comment</span></tt>)</a></li>
<li><a class="reference internal" href="#contents-command-contents" id="id34">Contents Command (<tt class="docutils literal"><span class="pre">?contents</span></tt>)</a></li>
<li><a class="reference internal" href="#default-attribute-value-command-default" id="id35">Default Attribute Value Command (<tt class="docutils literal"><span class="pre">?default</span></tt>)</a></li>
<li><a class="reference internal" href="#element-macro-definition-command-element" id="id36">Element Macro Definition Command (<tt class="docutils literal"><span class="pre">?element</span></tt>)</a></li>
<li><a class="reference internal" href="#encoding-command-encoding" id="id37">Encoding Command (<tt class="docutils literal"><span class="pre">?encoding</span></tt>)</a></li>
<li><a class="reference internal" href="#load-command-load" id="id38">Load Command (<tt class="docutils literal"><span class="pre">?load</span></tt>)</a></li>
<li><a class="reference internal" href="#restart-indentation-command-indent" id="id39">Restart Indentation Command (<tt class="docutils literal"><span class="pre">?indent</span></tt>)</a></li>
<li><a class="reference internal" href="#variable-command-variable" id="id40">Variable Command (<tt class="docutils literal"><span class="pre">?variable</span></tt>)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id9" id="id41">Macros</a><ul>
<li><a class="reference internal" href="#id10" id="id42">Attribute Groups</a></li>
<li><a class="reference internal" href="#id11" id="id43">Element Macros</a></li>
<li><a class="reference internal" href="#xslt-macro-example" id="id44">XSLT Macro Example</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h1><a class="toc-backref" href="#id12">Overview</a></h1>
<p>Compact XML is an alternative syntax for representing XML files. It uses
indentation to indicate nesting to give a python like feel, XPath based
prefixes to identify nodes, and has a macro system to shorten common XML
constructs. It is intended for writing element based XML files, especially
those where the XML elements share a common structure, such as XSLT files.</p>
<p>It is not well suited for markup based XML files, such as XHTML files, where
element nesting is less important.</p>
</div>
<div class="section" id="tutorial">
<h1><a class="toc-backref" href="#id13">Tutorial</a></h1>
<p>Familiarity with XML is assumed.</p>
<p>Compact XML uses a simple line based syntax for representing XML. The simplest
XML document is a single element:</p>
<pre class="literal-block">
Compact XML:

&lt;root

Equivalent in XML:

&lt;root/&gt;
</pre>
<p>Compact XML identifies each line by its prefix. Notice that the <tt class="docutils literal">&lt;</tt> prefix
is used to indicate that the line is an element, which is then followed by the
name of the element. Since the tag is not closed, this immediately leads to
nesting elements:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &lt;one
        &lt;two
        &lt;three

Equivalent in XML:

&lt;root&gt;&lt;one/&gt;&lt;two/&gt;&lt;three/&gt;&lt;/root&gt;
</pre>
<p>Compact XML uses indentation to indicate nesting, similar to the python
programming language. Such leading whitespace is used only to determine
nesting, and is not considered part of the XML. To add whitespace, or any
other textual data to an element, use the <tt class="docutils literal">&quot;</tt> prefix:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &quot;Hello, world.

Equivalent in XML:

&lt;root&gt;Hello, world.&lt;/root&gt;
</pre>
<p>Notice that text is indented just like elements are to show which element
contains the text. Notice the difference:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &lt;nested
        &quot;One
        &lt;nested
        &quot;Two

Equivalent in XML:

&lt;root&gt;&lt;nested/&gt;One&lt;nested/&gt;Two&lt;/root&gt;
</pre>
<p>Versus:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &lt;nested
                &quot;One
        &lt;nested
                &quot;Two

Equivalent in XML:

&lt;root&gt;&lt;nested&gt;One&lt;/nested&gt;&lt;nested&gt;Two&lt;/nested&gt;&lt;/root&gt;
</pre>
<p>Whitespace after the prefix is significant, and will show up in the XML.
However, things like trailing spaces can be difficult to see:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &quot; Hello, world.

Equivalent in XML:

&lt;root&gt; Hello, world. &lt;/root&gt;
</pre>
<p>Because of this, you can also quote the value, using either single(<tt class="docutils literal">'</tt>) or
double(<tt class="docutils literal">&quot;</tt>) quotes to quote a single line. So, the previous example can be
shown more clearly as:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &quot;' Hello, world. '

Equivalent in XML:

&lt;root&gt; Hello, world. &lt;/root&gt;
</pre>
<p>What about when we need to include a quote in a quoted value? Compact XML uses
a simple escaping rule, just double whichever quote character you're using:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &quot;' It''s a small world. '

Equivalent in XML:

&lt;root&gt; It's a small world. &lt;/root&gt;
</pre>
<p>Now, to include a new line in a text value, use a continuation. Values can be
continued on to the next line using the <tt class="docutils literal">\</tt> or <tt class="docutils literal">+</tt> continuation. With the
<tt class="docutils literal">\</tt> continuation, a newline is added, with the <tt class="docutils literal">+</tt> continuation the text
values are simply concatenated unmodified. Continuations must be indented to
the same level as the line they are continuing:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &quot;
        \Hello,
        \World.
        \

Equivalent in XML:

&lt;root&gt;
Hello,
World.
&lt;/root&gt;
</pre>
<p>Both names and values can be continued, but names can not use the <tt class="docutils literal">\</tt>
continuation, as names do not allow for whitespace. To illustrate, this is an
overly verbose way to specify the same thing as the previous example:</p>
<pre class="literal-block">
Compact XML:

&lt;
+r
+o
+o
+t
        &quot;
        \
        +H
        +e
        +l
        +l
        +o
        +,
        \World.
        \

Equivalent in XML:

&lt;root&gt;
Hello,
World.
&lt;/root&gt;
</pre>
<p>This is of course, ridiculous. Use the <tt class="docutils literal">+</tt> continuation for formatting when
you have a very long line and use the <tt class="docutils literal">\</tt> continuation when you want to
insert a new line.</p>
<p>Let's look at the last fundamental type of XML node, attributes. Attributes
are specified using the <tt class="docutils literal">&#64;</tt> prefix:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &#64;message=Hello, world.

Equivalent in XML:

&lt;root message=&quot;Hello, world.&quot;/&gt;
</pre>
<p>Remember value quoting? You can quote attribute values, but it's not required.
The only special rule is that whitespace between the equals sign and the start
of the attribute value is ignored, so the value will need to be quoted to
include whitespace at the start of an attribute value:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &#64;message=&quot; Hello, world. &quot;

Equivalent in XML:

&lt;root message=&quot; Hello, world. &quot;/&gt;
</pre>
<p>There is a special short form for attributes, that allows them to be included
in-line on the element statement. Quoting is also important here, as it's the
only way to include in-line attribute values with whitespace:</p>
<pre class="literal-block">
Compact XML:

&lt;root &#64;message=&quot;Hello, world.&quot;

Equivalent in XML:

&lt;root message=&quot;Hello, world.&quot;/&gt;
</pre>
<p>Notice that the <tt class="docutils literal">&#64;</tt> prefix may still be included for in-line attributes, but
that it can be omitted:</p>
<pre class="literal-block">
Compact XML:

&lt;root message=&quot;Hello, world.&quot;

Equivalent in XML:

&lt;root message=&quot;Hello, world.&quot;/&gt;
</pre>
<p>Namespaces are fully supported by compact XML. A namespace prefix can be
declared using the standard XML attribute:</p>
<pre class="literal-block">
Compact XML:

&lt;test:root
        &#64;xmlns:test=uri:testns

Equivalent in XML:

&lt;test:root xmlns:test=&quot;uri:testns&quot;/&gt;
</pre>
<p>However, there's no need to use the long form. The <tt class="docutils literal">#</tt> prefix can be used to
define a namespace prefix like so:</p>
<pre class="literal-block">
Compact XML:

&lt;test:root
        #test=uri:testns

Equivalent in XML:

&lt;test:root xmlns:test=&quot;uri:testns&quot;/&gt;
</pre>
<p>Namespaces work like attributes, and can be declared as either stand alone
statements or in-line:</p>
<pre class="literal-block">
Compact XML:

&lt;test:root #test=uri:testns

Equivalent in XML:

&lt;test:root xmlns:test=&quot;uri:testns&quot;/&gt;
</pre>
<p>Declaring default namespaces is just as simple:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        #uri:testns

Equivalent in XML:

&lt;root xmlns=&quot;uri:testns&quot;/&gt;
</pre>
<p>That covers all the basic statement types. See the reference documentation for
details on the less common nodes; comments(<tt class="docutils literal">!</tt>), processing
instructions(<tt class="docutils literal">&lt;?</tt>), and document type declarations(<tt class="docutils literal">&lt;!</tt>).</p>
<p>There is another class of statement that begins with the <tt class="docutils literal">?</tt> prefix. These
are commands for the compact XML converter, and do not directly correspond to
XML nodes. We'll take a look at some of the more common ones. First is
<tt class="docutils literal"><span class="pre">?default</span></tt>, which sets a default attribute value. When working with a
document that has many common attribute values, it can help to set this value.
Then, when an attribute is given with no value, the default is used instead:</p>
<pre class="literal-block">
Compact XML:

?default True
&lt;root &#64;flag

Equivalent in XML:

&lt;root flag=&quot;True&quot;/&gt;
</pre>
<p>If no default has yet been set, the value of the flag attribute would be an
empty string:</p>
<pre class="literal-block">
Compact XML:

&lt;root &#64;flag

Equivalent in XML:

&lt;root flag=&quot;&quot;/&gt;
</pre>
<p>If a single default isn't enough, variables can be defined using the
<tt class="docutils literal"><span class="pre">?variable</span></tt> statement. This sets a variable value that is global to the
document. To use the value of a variable, use the <tt class="docutils literal">$</tt> variable continuation.
The variable continuation is similar to the <tt class="docutils literal">+</tt> continuation, but instead of
inserting a literal value, inserts the value of the named variable:</p>
<pre class="literal-block">
Compact XML:

?variable value=True
&lt;root
        &#64;flag=
        $value

Equivalent in XML:

&lt;root flag=&quot;True&quot;/&gt;
</pre>
<p>Now, the interesting thing about variable evaluation is, if the variable
hasn't been defined, the statement is omitted from the output XML. This can be
used to conditionally include XML parts:</p>
<pre class="literal-block">
Compact XML:

?variable exists=
&lt;root
        &lt;one
        $exists
        &lt;two
        $does-not-exist

Equivalent in XML:

&lt;root&gt;&lt;one/&gt;&lt;/root&gt;
</pre>
<p>Notice that the <tt class="docutils literal">two</tt> element is omitted from the XML.</p>
<p>This may seem unnecessary, but is a useful part of defining macros. Element
macros use variables in a very similar way. Say you've got a very repetitive
XML file:</p>
<pre class="literal-block">
&lt;root&gt;
        &lt;item name=&quot;first&quot; description=&quot;stuff&quot; available=&quot;True&quot;/&gt;
        &lt;item name=&quot;second&quot; description=&quot;thingy&quot; available=&quot;True&quot;/&gt;
        &lt;item name=&quot;third&quot; description=&quot;other&quot; available=&quot;False&quot;/&gt;
&lt;/root&gt;
</pre>
<p>You can define an element macro using the <tt class="docutils literal"><span class="pre">?element</span></tt> command to include the
common parts:</p>
<pre class="literal-block">
Compact XML:

?element item
        &#64;name
        &#64;description
        &#64;available=True
        &lt;item
                &#64;name=
                $name
                &#64;description=
                $description
                &#64;available=
                $available
                ?contents
&lt;root
        item first stuff
        item &#64;name=second &#64;description=thingy
        item third other False

Equivalent in XML:

&lt;root&gt;&lt;item name=&quot;first&quot; description=&quot;stuff&quot; available=&quot;True&quot;/&gt;&lt;item
name=&quot;second&quot; description=&quot;thingy&quot; available=&quot;True&quot;/&gt;&lt;item
name=&quot;third&quot; description=&quot;other&quot; available=&quot;False&quot;/&gt;&lt;/root&gt;
</pre>
<p>Let's take a look at each part of the macro. First, we have the <tt class="docutils literal"><span class="pre">?element</span></tt>
command. All element macro definitions should occur before the document
starts. The <tt class="docutils literal"><span class="pre">?element</span></tt> command is followed by the name of the macro to
create, in this case <tt class="docutils literal">item</tt>.</p>
<p>Next is a list of attribute values, describing the parameters the macro
accepts. If a value is given, it's used as the default value for the parameter
if it is not passed. Here, only the <tt class="docutils literal">available</tt> parameter has a default
value, the others must be passed to the macro. The order the parameters are
defined in is important, as values can be passed to the macro both by position
and by name.</p>
<p>Then we have the actual element node that will be inserted for the macro:
<tt class="docutils literal">&lt;item</tt>. Next, each of the parameters we created are used as the values for
a similarly named attribute. Note that the same variable continuation syntax
is used for parameters, and the variable name corresponds to the name of the
defined parameter.</p>
<p>Last, we see the special element macro only command <tt class="docutils literal"><span class="pre">?contents</span></tt>. This is a
placeholder value for any extra macro contents that aren't part of a
parameter. Here, it's unused as the <tt class="docutils literal">&lt;item/&gt;</tt> element is empty.</p>
<p>In the next section, we see where the macro is called. The first uses
positional parameters, in the same order as the parameters were defined.
Notice, since the parameter values don't have spaces, there's no need to quote
them.</p>
<p>The second uses named parameters. Both positional and named parameters can be
used in the same macro call.</p>
<p>Finally, the third uses positional parameters, and overrides the default value
used for the <tt class="docutils literal">available</tt> parameter.</p>
<p>Remember when we were talking about undefined variables being useful for
element macros? This behaviour can be used to omit parts of the element macro
based on the parameters that are passed. For instance:</p>
<pre class="literal-block">
Compact XML:

?element item
        &#64;name
        &#64;description
        &#64;available=True
        &lt;item
                &#64;name=
                $name
                &#64;description=
                $description
                &#64;available=
                $available
                ?contents
&lt;root
        item first &#64;avaliable=False

Equivalent in XML:

&lt;root&gt;&lt;item name=&quot;first&quot; available=&quot;False&quot;/&gt;&lt;/root&gt;
</pre>
<p>Notice how the <tt class="docutils literal">description</tt> attribute just disappears when no value is
given for the description parameter.</p>
<p>There is a different attribute group macro available for working with
attributes.  The <tt class="docutils literal"><span class="pre">?attribute</span></tt> command defines such an attribute group.
Attribute group macros do not take parameters, only a group of attributes and
namespaces. Attribute groups are used with the <tt class="docutils literal">&#64;&#64;</tt> prefix:</p>
<pre class="literal-block">
Compact XML:

?attribute grouped
        &#64;message=Hello, world.
        &#64;type=Greeting
&lt;root
        &#64;&#64;grouped

Equivalent in XML:

&lt;root message=&quot;Hello, world.&quot; type=&quot;Greeting&quot;/&gt;
</pre>
<p>Attribute group statements can be used just like attributes, either in-line or
as a standalone statement.</p>
<p>That's all the major features of compact XML, you should be ready to start
writing!</p>
</div>
<div class="section" id="syntax">
<h1><a class="toc-backref" href="#id14">Syntax</a></h1>
<p>Compact XML uses a prefix based syntax, with each line generally comprising a
statement and each statement corresponding to a specific XML node. Statements
are comprised of a prefix followed by one or more expressions, and are usually
in one of the following three forms:</p>
<pre class="literal-block">
prefix [name expression]
prefix [value expression]
prefix [name expression] = [value expression]
</pre>
<p>Some statements, such as those representing XML elements allow nesting. The
indentation of each line is used to indicate nesting, and is always
significant.</p>
<p>Whitespace is significant throughout, with leading indentation used to
indicate nesting, and other whitespace being considered to be part of data
wherever applicable. Quoting is optional, and is only needed when it is
necessary to resolve ambiguity.</p>
<p>Most parser commands, those statements starting with <tt class="docutils literal">?</tt>, must appear
at the beginning of the document; The exceptions being <tt class="docutils literal"><span class="pre">?default</span></tt> and
<tt class="docutils literal"><span class="pre">?variable</span></tt> commands. Remaining document structure must follow XML form,
with a single optional document type declaration at the beginning of the
document and a required single root element or element macro. As with XML,
comments and processing instructions may exist before or after the root
element.</p>
</div>
<div class="section" id="expressions">
<h1><a class="toc-backref" href="#id15">Expressions</a></h1>
<p>Statements in compact XML are built from three kinds of expressions. There are
name expressions for XML names or internal names, value expressions for
everything else, and in-line expressions for brevity. Expressions always
evaluate to a single text value.</p>
<div class="section" id="literals">
<h2><a class="toc-backref" href="#id16">Literals</a></h2>
<p>All literal values are text values which span until the end of the line
(non-inclusive). Literals may contain other whitespace depending on the
context.</p>
</div>
<div class="section" id="names">
<h2><a class="toc-backref" href="#id17">Names</a></h2>
<p>Names follow the restrictions for XML names, and are used for both XML names
and for compact XML identifiers. This means they can not contain whitespace
and are limited to alphanumeric characters and three allowed punctuation
characters; dash (<tt class="docutils literal">-</tt>), underscore (<tt class="docutils literal">_</tt>), and period (<tt class="docutils literal">.</tt> ).</p>
</div>
<div class="section" id="continuations">
<h2><a class="toc-backref" href="#id18">Continuations</a></h2>
<p>Name or value expressions may be continued over several lines using one of the
special continuation prefixes on the following line. Continuations must be
indented to the same level as the line they are continuing.</p>
<p>The simplest is the addition continuation, which is prefixed with a plus sign
(<tt class="docutils literal">+</tt>). This simply continues the name or value onto the next line adding its
literal value.</p>
<p>Next there is the newline continuation, which is prefixed with a backslash
(<tt class="docutils literal">\</tt>). Then newline continuation is only valid for value expressions, as it
inserts a new line before appending its literal value. As names can not
contain whitespace such as new lines, it is disallowed in name expressions.</p>
<p>Finally there is the variable continuation, which is prefixed with a dollar
sign (<tt class="docutils literal">$</tt>). It is replaced by a variable value as defined for the name
specified.  If the variable is not defined, the whole expression is ignored.
Variable values can be defined globally as with the <tt class="docutils literal"><span class="pre">?variable</span></tt> command, or
inside element macros by parameters.</p>
</div>
<div class="section" id="value-expressions">
<h2><a class="toc-backref" href="#id19">Value Expressions</a></h2>
<p>Values are used for arbitrary text, and can include whitespace and new lines.
Whitespace is significant and is included in the value no matter where it
occurs, with the special case that whitespace after an '=' sign in name/value
pairs is ignored.</p>
<p>The components of value expressions can be either unquoted or quoted with
either single quotes (<tt class="docutils literal">'</tt>) or double quotes (<tt class="docutils literal">&quot;</tt>). The entire value is
either quoted or not, depending on if the first non-whitespace character
encountered is a quote. If a quote is found in an unquoted component, it is
used as is, and has no special meaning. Quotes in quoted literals can be
escaped by doubling the quote, as in <tt class="docutils literal">''</tt> or <tt class="docutils literal">&quot;&quot;</tt>.</p>
</div>
<div class="section" id="name-expressions">
<h2><a class="toc-backref" href="#id20">Name Expressions</a></h2>
<p>Names are used for XML names and internal compact XML names. Names can not
contain whitespace, and as such it is ignored in name expressions. Due to
this, name expression literals can't be quoted as there is no reason to do so.</p>
</div>
<div class="section" id="in-line-expressions">
<h2><a class="toc-backref" href="#id21">In-Line Expressions</a></h2>
<p>Attributes, attribute groups and namespace declarations can also be given
in-line on element statements. In-line expressions follow the same content
rules, however as in-line expressions are separated by whitespace, in-line
values must be quoted if they contain whitespace.</p>
<p>In-Line expressions can not be continued. Use the statement form if
continuations are needed.</p>
</div>
</div>
<div class="section" id="statements">
<h1><a class="toc-backref" href="#id22">Statements</a></h1>
<p>A statement in compact XML is a single indented line. The line may be
continued if one of the contained expressions uses one or more continuation
prefixes on the following lines ( <tt class="docutils literal">+</tt>, <tt class="docutils literal">\</tt>, or <tt class="docutils literal">$</tt> ).</p>
<p>Indentation indicates nesting. Only element macro definitions, attribute macro
definitions, elements and element macros may have nested statements indented
under them. Tabs are always treated as 8 spaces. Mixing of tabs and spaces for
indentation is discouraged, and can create confusion between lines that look
identical in a text editor, but are parsed differently.</p>
<p>Statements are identified by prefix, and are as follows:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">No Prefix:</th><td class="field-body"><a class="reference internal" href="#element-macro">Element Macro</a></td>
</tr>
<tr class="field"><th class="field-name">&lt;:</th><td class="field-body"><a class="reference internal" href="#element">Element</a></td>
</tr>
<tr class="field"><th class="field-name">&quot;:</th><td class="field-body"><a class="reference internal" href="#text">Text</a></td>
</tr>
<tr class="field"><th class="field-name">&#64;:</th><td class="field-body"><a class="reference internal" href="#attribute">Attribute</a></td>
</tr>
<tr class="field"><th class="field-name">&#64;&#64;:</th><td class="field-body"><a class="reference internal" href="#attribute-group">Attribute Group</a></td>
</tr>
<tr class="field"><th class="field-name">#:</th><td class="field-body"><a class="reference internal" href="#namespace">Namespace</a></td>
</tr>
<tr class="field"><th class="field-name">!:</th><td class="field-body"><a class="reference internal" href="#comment">Comment</a></td>
</tr>
<tr class="field"><th class="field-name">&lt;?:</th><td class="field-body"><a class="reference internal" href="#processing-instruction">Processing Instruction</a></td>
</tr>
<tr class="field"><th class="field-name">&lt;!:</th><td class="field-body"><a class="reference internal" href="#document-type-declaration">Document Type Declaration</a></td>
</tr>
<tr class="field"><th class="field-name">?attribute:</th><td class="field-body"><a class="reference internal" href="#attribute-group-definition-command">Attribute Group Definition Command</a></td>
</tr>
<tr class="field"><th class="field-name">?comment:</th><td class="field-body"><a class="reference internal" href="#comment-command">Comment Command</a></td>
</tr>
<tr class="field"><th class="field-name">?contents:</th><td class="field-body"><a class="reference internal" href="#contents-command">Contents Command</a></td>
</tr>
<tr class="field"><th class="field-name">?default:</th><td class="field-body"><a class="reference internal" href="#default-attribute-value-command">Default Attribute Value Command</a></td>
</tr>
<tr class="field"><th class="field-name">?element:</th><td class="field-body"><a class="reference internal" href="#element-macro-definition-command">Element Macro Definition Command</a></td>
</tr>
<tr class="field"><th class="field-name">?encoding:</th><td class="field-body"><a class="reference internal" href="#encoding-command">Encoding Command</a></td>
</tr>
<tr class="field"><th class="field-name">?indent:</th><td class="field-body"><a class="reference internal" href="#indent-command">Indent Command</a></td>
</tr>
<tr class="field"><th class="field-name">?load:</th><td class="field-body"><a class="reference internal" href="#load-command">Load Command</a></td>
</tr>
<tr class="field"><th class="field-name">?variable:</th><td class="field-body"><a class="reference internal" href="#variable-command">Variable Command</a></td>
</tr>
</tbody>
</table>
<div class="section" id="id1">
<span id="elements"></span><span id="element"></span><h2><a class="toc-backref" href="#id23">Element (<tt class="docutils literal">&lt;</tt>)</a></h2>
<p>XML elements are prefixed with <tt class="docutils literal">&lt;</tt>, followed by the name of the element as a
name expresssion.  Elements with a namespace are specified as normal for xml
with the prefix followed by a colon, then the remainder of the name. Nodes
contained within an element are indicated by indenting the contained nodes.</p>
<p>Both namespace and attribute statements can be nested as child elements or
in-line following the element name. If in-line the <tt class="docutils literal">&#64;</tt> can optionally be
omitted for attribute statements.</p>
<p>Namespace prefixes must be declared before they can be used, either globally
to the compact XML parser or by an explicit namespace declaration. As with
XML, namespaces declared on the element can be used by the element</p>
<p>For example, here are three nested elements:</p>
<pre class="literal-block">
Compact XML:

&lt;one
        &lt;two
                &lt;three


Equivalent in XML:

&lt;one&gt;&lt;two&gt;&lt;three/&gt;&lt;/two&gt;&lt;/one&gt;
</pre>
</div>
<div class="section" id="element-macro-no-prefix">
<span id="element-macros"></span><span id="element-macro"></span><h2><a class="toc-backref" href="#id24">Element Macro (<tt class="docutils literal">No Prefix</tt>)</a></h2>
<p>Element macros must first be defined by an <tt class="docutils literal"><span class="pre">?element</span></tt> <a class="reference internal" href="#element-macro-definition-command">element macro
definition command</a>. Attributes defined on the element macro will be used as
parameters for the macro. Parameters may be passed by position or by name.</p>
<p>Positional parameters require no prefix, and can only be passed in-line. Named
parameters and other attributes require the <tt class="docutils literal">&#64;</tt> prefix, even when passed
in-line, to disambiguate them from positional parameters.</p>
<p>Extra parameters and any nested statements are passed to the macro, and are
available using the <tt class="docutils literal"><span class="pre">?contents</span></tt> <a class="reference internal" href="#contents-command">contents command</a>. An element macro will
expand to one or more XML elements.</p>
<p>For details on creating and using macros, see the <a class="reference internal" href="#macros">macros</a> section.</p>
</div>
<div class="section" id="id2">
<span id="attributes"></span><span id="attribute"></span><h2><a class="toc-backref" href="#id25">Attribute (<tt class="docutils literal">&#64;</tt>)</a></h2>
<p>XML attributes are prefixed with <tt class="docutils literal">&#64;</tt> and must appear as the child of an
element or element macro They consist of a name expression, followed by and
optional <tt class="docutils literal">=</tt> sign and value expression.</p>
<p>If no value expression is given, the attribute will have the current default
attribute value as set by the <tt class="docutils literal"><span class="pre">?default</span></tt> <a class="reference internal" href="#default-attribute-value-command">default attribute value command</a>.</p>
<p>Named parameters are passed to <a class="reference internal" href="#element-macros">element macros</a> as attribute values.</p>
<p>For example, here is a single element with an attribute value:</p>
<pre class="literal-block">
Compact XML:

&lt;one
        &#64;name=value

Or:

&lt;one &#64;name=value

Or:

&lt;one name=value

Equivalent in XML:

&lt;one&gt;&lt;two&gt;&lt;three/&gt;&lt;/two&gt;&lt;/one&gt;
</pre>
</div>
<div class="section" id="id3">
<span id="attribute-groups"></span><span id="attribute-group"></span><h2><a class="toc-backref" href="#id26">Attribute Group (<tt class="docutils literal">&#64;&#64;</tt>)</a></h2>
<p>Attribute groups must first be defined by an <tt class="docutils literal"><span class="pre">?attribute</span></tt> <a class="reference internal" href="#attribute-group-definition-command">attribute group
definition command</a>. Once defined, they are included with the <tt class="docutils literal">&#64;&#64;</tt> prefix
followed by the macro name as a name expression.</p>
<p>Unlike <a class="reference internal" href="#element-macros">element macros</a> attribute groups do not have parameters or contents.</p>
<p>See the <a class="reference internal" href="#macros">macros</a> section for more details on creating and using attribute
groups.</p>
</div>
<div class="section" id="id4">
<span id="namespaces"></span><span id="namespace"></span><h2><a class="toc-backref" href="#id27">Namespace (<tt class="docutils literal">#</tt>)</a></h2>
<p>XML namespace declarations are prefixed with <tt class="docutils literal">#</tt> and must appear as the
child of an element or element macro. Namespaces are declared by a prefix name
as a name expression, followed by <tt class="docutils literal">=</tt>, and a value expression declaring the
namespace URI.</p>
<p>Namespace declarations are equivalent to an explicit namespace declaration
done with an attribute, in the <tt class="docutils literal">xmlns</tt> namespace.</p>
<p>For example, here is an element declared in a namespace:</p>
<pre class="literal-block">
Compact XML:

&lt;test:a
        #test=http://www.testuri.com

Or:

&lt;test:a #test=http://www.testuri.com

Or:

&lt;test:a &#64;xmlns:test=http://www.testuri.com

Equivalent in XML:

&lt;test:a xmlns:test=&quot;http://www.testuri.com&quot;/&gt;
</pre>
<p>Optionally, a default namespace can be declared as a stand alone value
expression. Remember to quote the value expression if it contains an <tt class="docutils literal">=</tt>
sign. For example:</p>
<pre class="literal-block">
Compact XML:

&lt;a
        #http://www.testuri.com

Or:

&lt;a #http://www.testuri.com

Or:

&lt;a &#64;xmlns=http://www.testuri.com

Equivalent in XML:

&lt;a xmlns=&quot;http://www.testuri.com&quot;/&gt;
</pre>
</div>
<div class="section" id="id5">
<span id="texts"></span><span id="text"></span><h2><a class="toc-backref" href="#id28">Text (<tt class="docutils literal">&quot;</tt>)</a></h2>
<p>Text is prefixed with <tt class="docutils literal">&quot;</tt> followed by a value expression.</p>
<p>For example, here is a multi-line text value:</p>
<pre class="literal-block">
Compact XML:

&lt;a
        &quot;Line one.
        \Line two.
        \Line three.

Equivalent in XML:

&lt;a&gt;Line one.
Line two.
Line three.&lt;/a&gt;
</pre>
</div>
<div class="section" id="id6">
<span id="comments"></span><span id="comment"></span><h2><a class="toc-backref" href="#id29">Comment (<tt class="docutils literal">!</tt>)</a></h2>
<p>Comments are prefixed with <tt class="docutils literal">!</tt> followed by a value expression.</p>
<p>For example, here is a multi-line comment:</p>
<pre class="literal-block">
Compact XML:

!Line one.
\Line two.
\Line three.

Equivalent in XML:

&lt;!--Line one.
Line two.
Line three.--&gt;
</pre>
</div>
<div class="section" id="id7">
<span id="processing-instructions"></span><span id="processing-instruction"></span><h2><a class="toc-backref" href="#id30">Processing Instruction (<tt class="docutils literal">&lt;?</tt>)</a></h2>
<p>Processing instructions are prefixed with <tt class="docutils literal">&lt;?</tt> followed by a target as a
name expression, an <tt class="docutils literal">=</tt> sign, and a value expression for the body of the
instruction. Notice the required <tt class="docutils literal">=</tt> sign, unlike XML. It will not appear in
the output document.</p>
<p>For example, here is a simple processing instruction:</p>
<pre class="literal-block">
Compact XML:

&lt;?target=instruction

Equivalent in XML:

&lt;?target instruction?&gt;
</pre>
</div>
<div class="section" id="id8">
<span id="document-type-declarations"></span><span id="document-type-declaration"></span><h2><a class="toc-backref" href="#id31">Document Type Declaration (<tt class="docutils literal">&lt;!</tt>)</a></h2>
<p>Document type declarations are prefixed with <tt class="docutils literal">&lt;!</tt> followed by <tt class="docutils literal">DOCTYPE</tt> and
a value expression specifying the rest of the document type as required by
XML.</p>
<p>Document type definition can only be specified at the top level of the
document, and only one is allowed per document. A document type declaration is
not required, however.</p>
<p>Due to limitations in the lxml library used, when compacting XML to compact
XML format, inline DTD definitions in DOCTYPE declarations are lost.</p>
<p>For example, the standard XHTML doctype declaration looks like this:</p>
<pre class="literal-block">
Compact XML:

&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;
\&quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;
&lt;html

Equivalent in XML:

&lt;!DOCTYPE html PUBLIC &quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;
&quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;
&lt;html/&gt;
</pre>
</div>
<div class="section" id="attribute-group-definition-command-attribute">
<span id="attribute-group-definition-commands"></span><span id="attribute-group-definition-command"></span><h2><a class="toc-backref" href="#id32">Attribute Group Definition Command (<tt class="docutils literal"><span class="pre">?attribute</span></tt>)</a></h2>
<p>The attribute group definition command is used to create an attribute group.
It expects a name literal to define the attribute group.</p>
<p>Any number of attributes or namespace declarations may be nested under the
command, and become part of the group. The group can be included in an element
or element macro using an <a class="reference internal" href="#attribute-group">attribute group</a>.</p>
<p>A simple attribute group would look like:</p>
<pre class="literal-block">
Compact XML:

?attribute common
        &#64;one=1
        &#64;two=2
        &#64;three=3
&lt;root
        &#64;&#64;common

Or:

&lt;root &#64;&#64;common

Equivalent in XML:

&lt;root one=&quot;1&quot; two=&quot;2&quot; three=&quot;3&quot;/&gt;
</pre>
<p>Attribute groups must be defined at the beginning of a compact XML document,
before any XML elements are created.</p>
<p>See the <a class="reference internal" href="#macros">macros</a> section for further details.</p>
</div>
<div class="section" id="comment-command-comment">
<span id="comment-commands"></span><span id="comment-command"></span><h2><a class="toc-backref" href="#id33">Comment Command (<tt class="docutils literal"><span class="pre">?comment</span></tt>)</a></h2>
<p>The comment command is used to include a compact XML comment in a source file.
It adds nothing to the expanded output, use the <a class="reference internal" href="#comment">Comment</a> command to create an
XML comment.</p>
<p>Any text may be included after the comment command, it is ignored.</p>
<p>An example:</p>
<pre class="literal-block">
Compact XML:

&lt;message
        ?comment Include your message here.
        &quot;Hello, world.

Equivalent in XML:

&lt;message&gt;Hello, world.&lt;/message&gt;
</pre>
</div>
<div class="section" id="contents-command-contents">
<span id="contents-commands"></span><span id="contents-command"></span><h2><a class="toc-backref" href="#id34">Contents Command (<tt class="docutils literal"><span class="pre">?contents</span></tt>)</a></h2>
<p>The contents command is used only within <a class="reference internal" href="#element-macro-definition-commands">element macro definition commands</a>
to show where extra contents passed to the element macro should be inserted.
By default, all contents will be inserted at the location of the command,
however the contents can be filtered to include only statements of a
particular type. To do so, give the prefix of the command type to include as
an argument, one of:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal">&lt;</tt></li>
<li><tt class="docutils literal">&#64;</tt></li>
<li><tt class="docutils literal">#</tt></li>
<li><tt class="docutils literal">&quot;</tt></li>
<li><tt class="docutils literal">!</tt></li>
<li><tt class="docutils literal">&lt;?</tt></li>
<li><tt class="docutils literal">?</tt></li>
</ul>
</blockquote>
<p>Note that attribute groups are expanded out into their component parts before
being filtered by the contents command.</p>
<p>Here is a simple macro demonstrating filtered contents:</p>
<pre class="literal-block">
Compact XML:

?element filtered
        &lt;root
                &lt;attributes
                        ?contents &#64;
                &lt;elements
                        ?contents &lt;
filtered
        !A comment.
        &#64;one=1
        &#64;two=2
        &lt;nested

Equivalent in XML:

&lt;root&gt;&lt;attributes one=&quot;1&quot; two=&quot;2&quot;/&gt;&lt;elements&gt;&lt;nested/&gt;&lt;/elements&gt;&lt;/root&gt;
</pre>
<p>Notice that the comment is ignored, and that the element and attribute
statements are included in differing spots based on the contents filters. See
the <a class="reference internal" href="#macros">macros</a> section for further details on using element macros.</p>
</div>
<div class="section" id="default-attribute-value-command-default">
<span id="default-attribute-value-commands"></span><span id="default-attribute-value-command"></span><h2><a class="toc-backref" href="#id35">Default Attribute Value Command (<tt class="docutils literal"><span class="pre">?default</span></tt>)</a></h2>
<p>This command sets the default attribute value used when no value is given for
an <a class="reference internal" href="#attribute">attribute</a> statement. It takes a value expression that sets that default
value. If no default has been set using <tt class="docutils literal"><span class="pre">?default</span></tt>, the default attribute
value is an empty (0-length) string.</p>
<p>Unlike most other commands, the default command can be used anywhere in a
document:</p>
<pre class="literal-block">
Compact XML:

root
        ?default 1
        &lt;first
                &#64;one
        ?default 2
        &lt;second
                &#64;two

Equivalent in XML:

&lt;root&gt;&lt;first one=&quot;1&quot; two=&quot;2&quot;/&gt;&lt;/root&gt;
</pre>
<p>This can be useful to set when using an XML language that has attribute flag
values which must all be set to <tt class="docutils literal">True</tt> or something similar.</p>
</div>
<div class="section" id="element-macro-definition-command-element">
<span id="element-macro-definition-commands"></span><span id="element-macro-definition-command"></span><h2><a class="toc-backref" href="#id36">Element Macro Definition Command (<tt class="docutils literal"><span class="pre">?element</span></tt>)</a></h2>
<p>The element macro definition command is used to create an element macro. It
expects a name literal to define the identifier used by the macro.</p>
<p>Macro parameters are defined as <a class="reference internal" href="#attribute">attribute</a> statements nested under the
definition. If a value is assigned to the parameter definition, it is used as
a default value for that parameter.</p>
<p>The expansion itself must be an element or element macro, although it can have
any normal element contents nested underneath it.</p>
<p>The <a class="reference internal" href="#contents-command">contents command</a> is only used within element macro definitions, and
allows for including unparameterized data in the macro.</p>
<p>A simple attribute group would look like:</p>
<pre class="literal-block">
Compact XML:

?element greeting
        &#64;message=Hello, world.
        &lt;greeting
                &#64;message=
                $message
                ?contents
&lt;root
        greeting
        greeting Goodbye.

Equivalent in XML:

&lt;root&gt;&lt;greeting message=&quot;Hello, world.&quot;/&gt;&lt;greeting message=&quot;Goodbye.&quot;/&gt;&lt;/root&gt;
</pre>
<p>Element macros must be defined at the beginning of a compact XML document,
before any XML elements are created.</p>
<p>See the <a class="reference internal" href="#macros">macros</a> section for further details on creating and using element macros.</p>
</div>
<div class="section" id="encoding-command-encoding">
<span id="encoding-commands"></span><span id="encoding-command"></span><h2><a class="toc-backref" href="#id37">Encoding Command (<tt class="docutils literal"><span class="pre">?encoding</span></tt>)</a></h2>
<p>The encoding command takes a value expression which specifies the encoding of
the output document. Note, unlike XML, this does not specify the encoding of
the compact XML file itself. Instead, compact XML files are always expected to
be in UTF-8 encoding.</p>
<p>The encoding command can only be given at the beginning of a compact XML
document, before any XML elements are defined.</p>
<p>A simple example:</p>
<pre class="literal-block">
Compact XML:

?encoding iso-8859-1
&lt;root

Equivalent in XML:

&lt;?xml version=&quot;1.0&quot; encoding=&quot;iso-8859-1&quot;?&gt;
&lt;root/&gt;
</pre>
</div>
<div class="section" id="load-command-load">
<span id="load-commands"></span><span id="load-command"></span><h2><a class="toc-backref" href="#id38">Load Command (<tt class="docutils literal"><span class="pre">?load</span></tt>)</a></h2>
<p>The load command takes a value expression specifying a file name to load
element macro definitions and attribute group definitions from. The behaviour
of the loader can be altered in the parser, if simple filenames are not
sufficient.</p>
<p>The file which is loaded must still be a valid compact XML file, and as such
must include the required root element even if it is never used.</p>
<p>External macros must be loaded at the beginning of a compact XML document,
before any XML elements are created.</p>
</div>
<div class="section" id="restart-indentation-command-indent">
<span id="indent-commands"></span><span id="indent-command"></span><h2><a class="toc-backref" href="#id39">Restart Indentation Command (<tt class="docutils literal"><span class="pre">?indent</span></tt>)</a></h2>
<p>Due to indentation based nesting, deeply nested documents can become difficult
to work with. This command, in <tt class="docutils literal"><span class="pre">?indent</span> restart</tt> and <tt class="docutils literal"><span class="pre">?indent</span> resume</tt>
pairs, provides a workaround.  When the restart command is given, indentation
is reset to the first column, but all following statements will still be
nested under the same element as the restart command until a resume command is
encountered. At which point indentation will be reset to the previous level.</p>
<p>Note, due to parser limitations, the resume command must not be indented.</p>
<p>Here's a simple example of the syntax:</p>
<pre class="literal-block">
Compact XML:

&lt;root
        &lt;nested
                ?indent restart
&lt;reset
?indent resume
                &lt;resume

Equivalent in XML:

&lt;root&gt;&lt;nested&gt;&lt;reset/&gt;&lt;resume/&gt;&lt;/nested&gt;&lt;/root&gt;
</pre>
<p>Notice how the reset element and resume element are in the same place in the
output document.</p>
</div>
<div class="section" id="variable-command-variable">
<span id="variable-commands"></span><span id="variable-command"></span><h2><a class="toc-backref" href="#id40">Variable Command (<tt class="docutils literal"><span class="pre">?variable</span></tt>)</a></h2>
<p>The variable command takes a name expression, an <tt class="docutils literal">=</tt> sign, and a value
expression. It creates a variable with the given name, and assigns it that
value. This variable is then added to the global scope, and any expression can
access it using a <tt class="docutils literal">$</tt> continuation.</p>
<p>Note that this can be used to create variables with whitespace or other
characters which are invalid for name expressions. Using such a variable value
in a name expression will trigger a run time error in the parser.</p>
<p>The global namespace can be shadowed in <a class="reference internal" href="#element-macro-definition-commands">element macro definition commands</a>,
so be careful using the same names for global variables as in element macro
definitions.</p>
<p>Variables can be defined anywhere in the document. As with the <cite>default
command</cite>, execution occurs top to bottom. Any expression on a later line can
access the variable.</p>
</div>
</div>
<div class="section" id="id9">
<span id="macros"></span><h1><a class="toc-backref" href="#id41">Macros</a></h1>
<p>Compact XML contains a macro syntax for defining commonly used elements and
groups of attributes. Element macros and attribute groups must be defined at
the top level of a document, before any XML nodes (including document type
definitions).</p>
<p>Once created, libraries of macros or groups can be kept in separate files and
loaded using the <a class="reference internal" href="#load-command">load command</a>.</p>
<div class="section" id="id10">
<h2><a class="toc-backref" href="#id42">Attribute Groups</a></h2>
<p>Attribute groups are defined with the <a class="reference internal" href="#attribute-group-definition-command">attribute group definition command</a>.
The declaration may contain any number of attribute (<tt class="docutils literal">&#64;</tt> statements) or
namespace (<tt class="docutils literal">#</tt> statements) declarations.</p>
<p>Attribute group names may contain namespace prefixes, but they aren't attached
to a particular namespace. Instead, the prefix itself is simply part of the
name.</p>
<p>When an attribute group is included by a <tt class="docutils literal">&#64;&#64;</tt> statement, the defined
attributes and namespaces are inserted at that location. This can be as a
child for an element or element macro, or even inside an element macro
definition.</p>
<p>Attribute groups can be nested to create groups of groups. Expansion of
attribute groups happens when used, not at definition.</p>
</div>
<div class="section" id="id11">
<h2><a class="toc-backref" href="#id43">Element Macros</a></h2>
<p>Element macros are used to declare a common form for an XML element. It allows
for shortening common structures, as well as declaring attributes by
declaration position as well as by name.</p>
<p>Element macros are defined using the <a class="reference internal" href="#element-macro-definition-command">element macro definition command</a>,
followed by a macro name and a list of parameters and default values. The
definition must contain one or more elements or element macros, which will be
what the macro is actually expanded to.</p>
<p>Macro names may contain namespace prefixes, but they aren't attached to a
particular namespace. Instead, the prefix itself is simply part of the name.</p>
<p>Element macros can be used within element macro definitions, if necessary. If
an error occurs, a stack trace will be shown listing all of the element macros
involved in the expansion.</p>
<p>Parameters are given as <a class="reference internal" href="#attributes">attributes</a>, and may have default values. The order
parameters are defined in is important, positional parameters will be assigned
to names in this same order. When expanded, both positional and named
parameters may be passed. If both are encountered, named parameters are
applied first and positional parameters are applied to the remaining
parameters. Any extra parameters are considered attribute contents, and can be
inserted using the <a class="reference internal" href="#contents-command">contents command</a> inside the macro definition.</p>
<p>Each macro definition creates its own parameter namespace scope, with the
global variable scope (as created by the <a class="reference internal" href="#variable-command">variable command</a> or by the parser)
as the containing scope.</p>
<p>If a macro has optional parts, it's important to take advantage of the
expression variable continuation behaviour. If an expression tries to expand a
variable or parameter name that doesn't exist, the entire statement (and any
nested children of the statement the expression is a part of), will be omitted
from the output document.  If a parameter has no default value, if used as a
variable it will be considered undefined and trigger this omission behaviour.</p>
<p>The most common use for element macros is when dealing with an element which
has several required attributes, often with commonly used values. Macros allow
the attributes to be assigned an order, and the short positional form to be
used.</p>
</div>
<div class="section" id="xslt-macro-example">
<h2><a class="toc-backref" href="#id44">XSLT Macro Example</a></h2>
<p>As a detailed example, presented here is a sample set of element macro
definitions for XSLT 1.0. The <tt class="docutils literal">xsl:</tt> prefix is used for these macro
definitions to avoid confusion, if you never deal with namespaces this could
easily be removed for brevity. This covers the commonly used attributes, all
others must be specified by name. All elements are mapped, however.</p>
<pre class="literal-block">
?element xsl:stylesheet
        &#64;version=1.0
        &lt;xsl:stylesheet
                #xsl=http://www.w3.org/1999/XSL/Transform
                &#64;version=
                $version
                ?contents
?element xsl:include
        &#64;href
        &lt;xsl:include
                &#64;href=
                $href
                ?contents
?element xsl:import
        &#64;href
        &lt;xsl:import
                &#64;href=
                $href
                ?contents
?element xsl:strip-space
        &#64;elements
        &lt;xsl:strip-space
                &#64;elements=
                $elements
                ?contents
?element xsl:preserve-space
        &#64;elements
        &lt;xsl:preserve-space
                &#64;elements=
                $elements
                ?contents
?element xsl:template
        &#64;match
        &#64;name
        &#64;priority
        &#64;mode
        &lt;xsl:template
                &#64;match=
                $match
                &#64;name=
                $name
                &#64;priority=
                $priority
                &#64;mode=
                $mode
                ?contents
?element xsl:apply-templates
        &#64;select
        &#64;mode
        &lt;xsl:apply-templates
                &#64;select=
                $select
                &#64;mode=
                $mode
                ?contents
?element xsl:apply-imports
        &lt;xsl:apply-imports
                ?contents
?element xsl:call-template
        &#64;name
        &lt;xsl:call-template
                &#64;name=
                $name
                ?contents
?element xsl:namespace-alias
        &#64;result-prefix
        &#64;stylesheet-prefix
        &lt;xsl:namespace-alias
                &#64;result-prefix=
                $result-prefix
                &#64;stylesheet-prefix=
                $stylesheet-prefix
                ?contents
?element xsl:element
        &#64;name
        &#64;namespace
        &#64;use-attribute-sets
        &lt;xsl:element
                &#64;name=
                $name
                &#64;namespace=
                $namespace
                &#64;use-attribute-sets=
                $use-attribute-sets
                ?contents
?element xsl:attribute
        &#64;name
        &#64;namespace
        &lt;xsl:attribute
                $&#64; name = &#64;name
                $&#64; namespace = &#64;namespace
                ?contents
?element xsl:attribute-set
        &#64;name
        &#64;use-attribute-sets
        &lt;xsl:attribute-set
                &#64;name=
                $name
                &#64;use-attribute-sets=
                $use-attribute-sets
                ?contents
?element xsl:text
        &#64;disable-output-escaping
        &lt;xsl:text
                &#64;disable-output-escaping=
                $disable-output-escaping
                ?contents
?element xsl:processing-instruction
        &#64;name
        &lt;xsl:processing-instruction
                &#64;name=
                $name
                ?contents
?element xsl:comment
        &lt;xsl:comment
                ?contents
?element xsl:copy
        &#64;use-attribute-sets
        &lt;xsl:copy
                &#64;use-attribute-sets=
                $use-attribute-sets
                ?contents
?element xsl:value-of
        &#64;select
        &lt;xsl:value-of
                &#64;select=
                $select
                ?contents
?element xsl:number
        &lt;xsl:number
                ?contents
?element xsl:for-each
        &#64;select
        &lt;xsl:for-each
                &#64;select=
                $select
                ?contents
?element xsl:if
        &#64;test
        &lt;xsl:if
                &#64;test=
                $test
                ?contents
?element xsl:choose
        &lt;xsl:choose
                ?contents
?element xsl:when
        &#64;test
        &lt;xsl:when
                &#64;test=
                $test
                ?contents
?element xsl:otherwise
        &lt;xsl:otherwise
                ?contents
?element xsl:sort
        &#64;select
        &lt;xsl:sort
                &#64;select=
                $select
                ?contents
?element xsl:variable
        &#64;name
        &#64;select
        &lt;xsl:variable
                &#64;name=
                $name
                &#64;select=
                $select
                ?contents
?element xsl:param
        &#64;name
        &#64;select
        &lt;xsl:param
                &#64;name=
                $name
                &#64;select=
                $select
                ?contents
?element xsl:copy-of
        &#64;select
        &lt;xsl:copy-of
                &#64;select=
                $select
                ?contents
?element xsl:with-param
        &#64;name
        &#64;select
        &lt;xsl:with-param
                &#64;name=
                $name
                &#64;select=
                $select
                ?contents
?element xsl:key
        &#64;name
        &#64;match
        &#64;use
        &lt;xsl:key
                &#64;name=
                $name
                &#64;match=
                $match
                &#64;use=
                $use
                ?contents
?element xsl:decimal-format
        &lt;xsl:decimal-format
                ?contents
?element xsl:message
        &#64;terminate
        &lt;xsl:message
                &#64;terminate=
                $terminate
                ?contents
?element xsl:fallback
        &lt;xsl:fallback
                ?contents
?element xsl:output
        &#64;method
        &#64;indent
        &#64;media-type
        &lt;xsl:output
                &#64;method=
                $method
                &#64;indent=
                $indent
                &#64;media-type=
                $media-type
                ?contents
</pre>
</div>
</div>
</div>
</body>
</html>
